/** @file conartist.h
 * The main include file for ConArtist.
 * @note This should be the only include file needed for a ConArtist
 * client.
 */

/*
 * Licensed to the ConArtist Development Team (CADT).
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 * The CADT licenses this file to you under the Apache License, 
 * Version 2.0 (the "License"); you may not use this file except in
 * compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/** @mainpage ConArtist Library API
 *
 * Documentation for the ConArtist API that is implemented as a shared
 * library.
 */

/** @defgroup LIC Licence
Licensed to the ConArtist Development Team (CADT).
See the NOTICE file distributed with this work for additional
information regarding copyright ownership.
The CADT licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
 */

#ifndef CONARTIST_H
#define CONARTIST_H

#include <sys/types.h>

#include <apr.h>
#include <apr_pools.h>
#include <apr_tables.h>
#include <apr_hash.h>
#include <apr_network_io.h>

#define CA_VER_MAJOR     0        /**< Major version of ConArtist */
#define CA_VER_MINOR     0        /**< Minor version of ConArtist */
#define CA_VER_RELEASE   1        /**< Release version of ConArtist */
#define CA_VER_QUALITY   "alpha"  /**< Quality of ConArtist */

/** @defgroup ConArtist Dynamic Modules
 * ConArtist makes use of dynamically loaded modules to provide its
 * functionality.
 * @{
 */
#define CAM_STORE     1     /**< Library provides a type of store */
#define CAM_PIPE      2     /**< Library provides a pipe implementation */

#define CAM_ERR_TYPE    100 /**< Incorrect type of library for operation */

/** The caModule structure is used by all dynamically loaded modules
 * used by ConArtist. It defines the minimum attributes that all dyanmic 
 * modules MUST declare to be usable. The type should be one of the CAM_
 * constants to ensure that it can be loaded correctly.
 *
 * The structure is extended by the different uses of the module.
 *
 * The structure must be called ConArtistModule within the library for
 * ConArtist to find it.
 */
struct caModule {
    apr_int32_t verMajor;            /**< major version component of module */
    apr_int32_t verMinor;            /**< minor version component of module */
    char *name;                      /**< name of module */
    char type;                       /**< type of module, CAM_ constant */
    apr_status_t (*modInit)(apr_pool_t *); /**< initialisation function */
    apr_status_t (*modFini)(void);   /**< uninitialisation function */
};

/** @fn apr_status_t findDSO(const char *path)
 * Function to find a DSO from those already loaded.
 * @param path The full path to the module
 */ 
apr_status_t findDSO(const char *);

/** @} */

/** @defgroup GENERAL ConArtist General
 * @{
 */

/** @fn apr_status_t caInit(apr_pool_t *parent)
 * Initialise the ConArtist libraries.
 * @param parent The pool we will be a child of.
 * @note If parent is NULL a top level pool will be created.
 */
apr_status_t  caInit(apr_pool_t *);

/** @fn apr_status_t caTerminate(void *data)
 * Shutdown the libraries and all processes controlled by it.
 * @param data Pointer to data to use when shutting down.
 */
apr_status_t caTerminate(void *);

/** @fn const char *caGetVersion(void);
 * Get the version of the library.
 */
const char *caGetVersion(void);

/** @fn const char *caLastError(void)
 * Return a string describing the last configuration error.
 * @note NB This also resets the error string.
 */
const char *caLastError(void);

/** When getting content from a ConArtist instance this structure
 * will be used to specify what is requested and then return it.
 * Content that is cached (or simply available on disk)
 * will be returned as a filename, whereas dynamic content
 * will be returned as a pointer and length. The content type may or may
 * not be set. The pool provided when requesting the data will be used
 * for the allocation of the structure and content within it.
 * The output fields will be NULL'd when passed in, so the caller need
 * not worry about clearing them prior to calling caGetContent. 
 */
struct caContent {
    /* Input */
    apr_pool_t *pool;        /**< Pool to use for allocations */

    const char *hostname;    /**< Hostname request is for */
    apr_port_t port;         /**< Port request was made on */
    const char *uri;         /**< The full URI requested */
    apr_table_t *headers_in; /**< Request headers */

    /* TODO - add session variables */
    const char *sess_cookie; /**< Session cookie */
    /* Output */
    char *filename;          /**< On disk filename for content */
    apr_size_t fLen;         /**< Length of file saved on disk */
    void *data;              /**< Pointer to content */
    apr_size_t dataLen;      /**< Size of available data (in bytes) */
    char *contentType;       /**< Content type */
    char *encoding;          /**< Content encoding */
};

/** @fn apr_status_t caGetContent(struct caContent *req)
 * Get content from the ConArtist library.
 * @param req Pointer to a caContent structure detailing the request. This
 *            will contain the content when it returns.
 * @returns APR_SUCCESS if req contains valid content, any other value
 *          signifies the content could be created.
 */
apr_status_t caGetContent(struct caContent *);


/** @} */

/** @defgroup CONFIG Configuration Directives
Configuration of ConArtist is done using XML files. Configuration files
may be either on the local machine or contained in a configured store.
Not all configuration directives are available when the configuration
file is contained in a defined store.

@pre
    Top Level Configuration
           Directive               Local              Store

      DefaultLogLevel                X
      DSOPath                        X
      Generator                      X                  X
      Log                            X
      Store                          X                  X


 */
#endif /* CONARTIST_H */
